LoadDatabase

Definition:

LoadDatabase(database[, buildonserver[, createtype[, encryptonserver]]])

 

Description:

Update a specified local database on a mobile device, by downloading selected data from selected Data Sources configured to use the specified local database.

See Notes below for details of how to select which records are downloaded and from which Data Sources.

 

Platforms:

All

 

Parameters:

database - required

String containing the name of the local database that you want to update. Enter the name without the file extension. See Local Data Storage on Mobile Devices for details of local database names under different Platforms.

Data Source tables that are configured to use the database specified here in their Device Database Property will be available for inclusion in the download – but see Notes below for information about selecting Data Sources to be downloaded.

 

buildonserver - optional

This parameter is no longer used but if you need to include it because you want to include later parameters, set it to "False".

 

createtype - optional

String defining how the downloaded data will be incorporated into the local database on the device.

Possible values are:

"create"

Creates a new table within the local database for each downloaded table, deleting the previous table(s) but leaving any tables not included in the download in their previous state. All tables for which the download completes successfully will be overwritten, but if the download fails for a particular table that table will not be updated.

 

"append"

Appends the data to the existing table(s). This is the default value if this parameter is omitted.

 

"update"

Inserts and updates data returned into the existing table(s) (must have a primary key defined).

 

encryptonserver - optional

This parameter is no longer required and can be omitted.

 

Returns:

nothing

 

Notes:

  • The optional parameters buildonserver and encryptonserver are no longer supported and if specified, e.g. where a Script is intended to run on multiple Platforms, will be ignored.

  • The table(s) downloaded to the device using this Method will be incorporated into the existing local table(s) on the device according to the value of the createtype parameter. Any local tables not included in the download will remain unchanged after the download.

  • The database parameter specifies the local database on the mobile device which is to be updated by this Method.

    By default, this Method will include all Data Source tables set to use the specified database, i.e. that have this database named in their Device Database Property. Where the target is an ADO database, you can select which records are to be downloaded for each table using the Filter Property for ADO Database Data Sources or the SQL Statement Property for Custom Tables.

    If the Data Source is a Custom Table, the SQL Statement Property should contain the full Select statement e.g. "SELECT * FROM table1 WHERE user = 'John'". The SELECT statement can start with SELECT or SELECT DISTINCT and columns can be referred to using the format <table>.<column> but <table>.* is not supported. Only Custom Tables where the Mode Property is set to Remote ADO can be updated using LoadDatabase.

    Otherwise, if the Data Source is an ADO Database Data Source, the Filter Property is used and should contain only a 'where' clause, excluding the word 'where', e.g. "user = 'John'". Columns can be referred to using the format <table>.<column> but <table>.* is not supported.

    In either case, when specifying your SQL Select statement you may want to specify the order in which records should be returned by including an ORDER BY clause, e.g. "SELECT * FROM table1 WHERE user = 'John' ORDER BY table1.userID".

    If the Filter or SQL Statement Property for a table is blank all records in that table will be downloaded.

    • You can change a SQL statement specified in the Filter/SQL Statement Property for a Data Source within App Manager. This allows you to change the records to be selected without having to edit and republish your app. To do this display the Properties for the relevant app in App Manager and then use the Data Sources button.

     

    You can change the default mode, which includes all Data Sources set to use the specified database, such that only some of those Data Sources will be included. You do this using the SetSelectString Method. SetSelectString determines which tables are included in a download using the LoadDatabase Method and also allows you to specify a SQL Select statement to be used to specify which records should be downloaded for each table.

    When you call the LoadDatabase Method, all relevant Data Sources will be included in the download, unless you have previously called the SetSelectString Method, when:

    • The first call to SetSelectString resets the list of Data Source tables that will be downloaded to only those specified in a SetSelectString call.

    • If the SetSelectString call includes a SQL Select statement, this will be used to select which records are downloaded for this table in preference to any SQL Select statement in the Filter/SQL Statement Property. If the Select statement is set to an empty string, "", the Filter/SQL Statement Property will be used as in the default mode.

    • Subsequent SetSelectString calls add Data Sources to this list.

    • After a call to any of the Synchronise, LoadDataSource or LoadDatabase Methods, the Data Source list is cleared and LoadDatabase reverts back to its default mode of operation, until another SetSelectString call is made.

    • If you want to include both Database and Web Service Data Sources and create a SetSelectString list to define the data downloaded, you will need to call SetSelectString for each Web Service Data Source as well as the database Data Source(s). For each Web Service, you would simply leave the Select string blank.

  • If you have any Local Only Custom Tables within the local database specified in the LoadDatabase call, these tables cannot be updated from a remote data source, so you must use SetSelectString, as described above, to specify the data tables to be included in the download, otherwise the 'local only' tables may be deleted. Preferably, Local Only Custom Tables should be stored in their own database(s) on the mobile device separate from remote Data Source tables.

  • By default, a progress bar is displayed to show the progress of the download and the user can cancel the download whilst it is in progress. The SetApplicationOption Method allows you to reduce or turn off the messages displayed with the progress bar or to replace it with the device's standard busy indicator instead. It also allows you to disable/re-enable the ability to cancel the download.

    If the user cancels the download, the calling Script will continue.

  • The Digitise app will pause and users will not be able to use the app whilst the data transfer takes place. If you are downloading from a remote database and you want to be able to continue to use the app, see the Synchronise Method instead.

  • You cannot call this Method if there is already an ongoing asynchronous data transfer in progress.

  • This Method isn't relevant for use with Custom Views.

  • You cannot use this Method where you have stored data items such as photos and videos to file rather than in a local database table.

  • You can't use this Method with Web API Data Sources. If you have Web API Data Sources and you want to call LoadDatabase, you will either have to configure a list of Data Sources to be included using SetSelectString as described above or make sure that any Web API Data Sources have their Device Database Property set to use a different local database than the one specified in your call to LoadDatabase.

  • On Android devices, note the following potential issues relating to large data objects, particularly photographs and videos:

    • |

    • When downloading large binary fields (i.e. photos or videos) on lower power/memory devices the Digitise Apps Client may fail to download some large bitmaps/videos into the application database. An Out Of Memory error message will be displayed. The overall download should complete but some records may not contain the downloaded image/video data, having Null values in the columns where the Out Of Memory issue occurred. This problem may occur where you are trying to download photos/videos taken on one device, with a higher megapixel camera, to another less powerful device.


See also:

Synchronise